Power Programmierung 2

home *** CD-ROM | disk | FTP | other *** search

/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / c / library / dos / communic / ckit176c / ckit.doc < prev next >

Wrap

Text File | 1991-04-06 | 162.4 KB | 4,039 lines

CKIT DOOR building Toolkit Library Version 1.76C Reference Manual Distributed By Data-Comp Information Systems P.O. Box 5895 Maryville, Tenn. 37802-5895 (615) 982-6537 (Hayes Ultra V.32, public line) (615) 982-8723 (Hayes Ultra V.32, private line) (615) 982-6512 (USR HST Dual Standard V.32, private line) (615) 970-7418 (USR HST Dual Standard V.32, private line) Copyright (c) 1990 Rickie W. Belitz Introduction Introduction CKIT Library is an extensive library of C runtime routines that allow easy door program implementation using PCBoard 12.0 through 14.x, WILDCAT! systems, (all versions), GAP BBS, SPITFIRE BBS and other systems using standard DOOR.SYS file along with RBBS-PC, QuickBBS, Remote Access and other systems using DORINFOx.DEF files. In addition, CKIT will also utilize a file called GENERIC.SYS. This file will allow CKIT to work on ANY BBS system. See section on GENERIC.SYS for more information. Some of CKIT Library's features include interrupt driven I/O, 16550AN UART support,provides information available from the PCBoard .sys files, database files, multi-node support (file sharing), multi-BBS support, local sysop function keys and many more utilities are included for the door author. The CKIT Library routines are written in Assembly language using SLR's Optasm and MSC 6.0. The routines are compatible with Microsoft C, Microsoft QuickC, TURBO C, and TURBO C++. CKIT Library supports the small, and medium models. Microsoft is a registered trademark, and QuickC is a trademark of the Microsoft Corporation. TURBO C is a registered trademark of Borland International Inc. TURBO C++ is a registered trademark of Borland International Inc. PCBoard is a registered trademark of Clark Development Company. WILDCAT! is a registered trademark of Mustang Software. SPITFIRE is a registered trademark of Buffalo Creek Software RBBS-PC is copyright (c) Tom Mack, Capital PC Software Exchange QUICKBBS is copyright (c) Adam Hudson REMOTE ACCESS is copyright (c) Andrew Milner, Continental Software Registration The unregistered library will display "Unregistered copy etc." as part of the signoff message. The registered version eliminates this signoff msg at the time the door is closed. Please see the registration information below. A lot of effort has gone into CKIT, to make sure it would operate reliably and with little effort on the part of the door author. If find the program of use, please register it and help support the Shareware method of program distribution. Registering will also help fund further development of the libraries. CKIT is being distributed as Shareware. The registration includes: ∙ A disk with the latest version of CKIT, registered to you. ∙ Self-Registration program for future releases of CKIT ∙ Technical support via electronic mail . A LARGE memory model of CKIT. (download from Data-Comp BBS) For more information see the addresses, phone numbers listed at the end of this document. Global Variables Global Variables used by all systems The CKIT Library defines a number of variables in the ckit.h header file. Through proper use, these variables allow the programmer to customize the CKIT Library functions to meet particular application program's needs. DUMP_USER ------------------------------------------------------------------- Defined As: short DUMP_USER; Description: This variable will be set if the user hangs up, his/her time runs out, carrier is lost, or if the sysop wants to return the user to the BBS system using function key F8. You should check this flag in all major loops in the door program. FORCEOFFHOOK ------------------------------------------------------------------- Defined As: short FORCEOFFHOOK Description: This variable should be set to TRUE or FALSE in the CKIT.H file. If this variable is TRUE, the modem will be placed OFF-HOOK if carrier is dropped in the door before returning to the system. If FORCEOFFHOOK is false, the door will not take the modem off-hook. See CKIT.H USERFILE ------------------------------------------------------------------- Defined As: short USERSFILE Description: This variable should be set to TRUE or FALSE in the CKIT.H file. If this variable is TRUE, CKIT will open the Users file and those variables will be available. If not, only the PCBOARD.SYS file will be opened and the user information will not be available. See CKIT.H. option ------------------------------------------------------------------ Defined As: unsigned char option; Description: This variable is set to indicate how the user was logged off the system. There are 5 macro's in the CKIT header file that describes each. THIS INFORMATION IS AVAILABLE ONLY AFTER YOU CALL CLOSE_DOOR(); #define EXITDOOR 0 Normal door exit #define NOCARRIER 1 Dropped carrier* #define TIMEOUT 2 Keyboard timeout* #define SYSOP_O 3 Sysop request* #define SYSTEMTIME 4 System time expired* #define LOGOFF 5 User logged off* * These are normally handled internally by CKIT COMPATIBILITY Global Variables logoff_color pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short logoff_color; Description: This variable used to specifiy the color of the exit_msg[] string. (See below). See the ckit.h file for colors available. Example: logoff_color = (green). NOTE: If not specified, the default color is violet. exit_msg pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char exit_msg[40]; Description: This should be a NULL terminated C string. This is used to specify the exit back to BBS msg. MAX. 40 CHARS! Example: strcpy(exit_msg, "Returning to system, Please wait..."); NOTE: If not specified, the default message is the same as above. logoff_msg pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char logoff_msg[40]; Description: This should be a NULL terminated C string. This is used to specify the logoff message desired. MAX. 40 CHARS! Example: strcpy(exit_msg, "Thanks for calling! ..."); NOTE: If not specified, the default message is the same as above. display pcboard.sys ------------------------------------------------------------------ Defined As: short display; Description: This variable is set to indicate the status of the local BBS display. file. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only printer pcboard.sys ------------------------------------------------------------------ Defined As: short printer; Description: This variable is set to indicate the status of the BBS printer. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only COMPATIBILITY Global Variables pagebell pcboard.sys ------------------------------------------------------------------ Defined As: short pagebell; Description: This variable is set to indicate the status of the BBS pagebell. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only callalarm pcboard.sys ------------------------------------------------------------------ Defined As: short callalarm; Description: This variable is set to indicate the status of the BBS caller alarm. TRUE/FALSE 0 = No, 1 = yes. Useful with 12.0 - > 14.x pcboard.sys usage only PCB pcboard.sys ------------------------------------------------------------------ Defined As: short PCB; Description: This variable is set to indicate whether CKIT found a PCBoard.sys file. TRUE/FALSE 0 = No, 1 = yes. PCB12 pcboard.sys wildcat! ------------------------------------------------------------------ Defined As: short PCB12; Description: This variable is set to indicate whether CKIT found a PCBoard version 12.0 pcboard.sys file or not. TRUE/FALSE 0 = No, 1 = yes. WILDCAT pcboard.sys wildcat! ------------------------------------------------------------------ Defined As: short WILDCAT; Description: This variable is set to indicate whether CKIT found a WILDCAT callinfo.bbs file or not. TRUE/FALSE 0 = No, 1 = yes. RBBS RBBS-PC dorinfox.def ------------------------------------------------------------------ Defined As: short RBBS; Description: This variable is set to indicate whether CKIT found a RBBS type DORINFOx.DEF file or not. TRUE/FALSE 0 = No, 1 = yes. GENERIC any BBS system ------------------------------------------------------------------ Defined As: short GENERIC; Description: This variable is set to indicate whether CKIT found a GENERIC.SYS file. TRUE/FALSE 0 = No, 1 = yes. COMPATIBILITY Global Variables graphics pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short graphics; Description: This variable is set to indicate the status of the user graphics mode. Supports ANSI X3.64 standard commands. TRUE/FALSE 0 = No, 1 = yes. error_connection pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: short error_connection; Description: This variable is set to indicate the status of the modem error_connection. TRUE/FALSE 0 = No, 1 = yes. local pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short local; Description: This variable is set to indicate the status of the local/remote operation of door. TRUE/FALSE 0 = No, 1 = yes. expert pcboard.sys door.sys ------------------------------------------------------------------ Defined As: short expert; Description: This variable is set to indicate the status of the expert/novice mode of user. TRUE/FALSE 0 = No, 1 = yes. event_active pcboard.sys ------------------------------------------------------------------ Defined As: short event_active; Description: This variable is set to indicate the status of the system event. TRUE/FALSE 0 = No, 1 = yes. Useful with 14.x pcboard.sys usage only slide_event pcboard.sys ------------------------------------------------------------------ Defined As: short slide_event; Description: This variable is set to indicate whether the system event can be moved or not. TRUE/FALSE 0 = No, 1 = yes. Useful with 14.x pcboard.sys useage only sysop_next pcboard.sys ------------------------------------------------------------------ Defined As: char sysop_next[2]; Description: This C string indicates the status of the Sysop Next flag. N = sysop next, X = exit to system, space = nothing pending. Useful with 12.0 - > 14.x pcboard.sys usage only COMPATIBILITY Global Variables netchat pcboard.sys ------------------------------------------------------------------ Defined As: char netchat[2]; Description: This C string indicates the status of the the user's netchat. U = Unavailable, A = available. Useful with 12.0 - > 14.x pcboard.sys usage only aport pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char aport[2]; Description: This C string is an ASCII string of the com port in use as determined. See also port. bps_open pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: char bps_open[6]; Description: This C string is an ASCII string of the BBS's DTE to modem baud rate. Not available with PCBoard 12.0 baud_rate pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char baud_rate[6]; Description: This C string is an ASCII string of the callers baud rate. firstname pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char firstname[16]; Description: This C string is an ASCII string of the caller first name. password pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: char password[13]; Description: This C string is an ASCII string of the caller password. fullname pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ defined As: char fullname[26]; Description: This C string is an ASCII string of the caller fullname. COMPATIBILITY Global Variables page_length pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: BYTE page_length; Description: Page length of user. This information is not available with PCBoard 12.0 so there is a default of 23. The door author can adjust as desired. This is also used by display_file(). Setting to 0 equals continous. (NON-STOP). language pcboard.sys ------------------------------------------------------------------ defined As: char language[5]; Description: This C string is an ASCII string of the caller language. Space = English time_logged pcboard.sys door.sys wildcat! ------------------------------------------------------------------ defined As: char time_logged[6]; Description: This C string is an ASCII string of the time caller logged onto the BBS. event_time pcboard.sys door.sys ------------------------------------------------------------------ defined As: char event_time[6]; Description: This C string is an ASCII string of the system event time of the BBS as HH:MM. Not available with PCBoard 12.0 time_on pcboard.sys ------------------------------------------------------------------ Defined As: short time_on; Description: This variable indicates the time in minutes past midnight the user logged on. prev_used pcboard.sys ------------------------------------------------------------------ Defined As: short prev_used; NOTE: N/A for PCBoard 12.0 Description: This variable indicates the time in minutes used in previous calls today. user_record pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: unsigned short user_record; Description: This variable holds the user record number. time_limit pcboard.sys ------------------------------------------------------------------ Defined As: short time_limit; Description: This variable holds the user BBS system time limit in minutes. COMPATIBILITY Global Variables time_added pcboard.sys ------------------------------------------------------------------ Defined As: short time_added; Description: This variable holds the Area user time added so far in minutes. min_left pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: short min_left; Description: This variable holds the user time left on system. port pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: short port; Description: This variable holds the com port in use. Equal to 0 if local mode. node[] pcboard.sys door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char node[3]; NOTE: N/A for PCBoard 12.0 Description: This string holds the node in use. Equal to space if no network active. *conferences door.sys wildcat! ------------------------------------------------------------------ Defined As: char *conferences; Description: This a pointer to a string of conferences/forums the user is registered in. parity door.sys wildcat! ------------------------------------------------------------------ Defined As: short parity; Description: Represent the ASCII character of parity in use. Note this NOT a string. It will either be ASCII 7 (0x37) or 8 (0x38). protocol pcboard.sys door.sys wildcat! ------------------------------------------------------------------ Defined As: char protocol[15] Description: String containing the users current protocol setting. PCBoard/GAP/SPITFIRE will only list the 1st char. of the protocol, WILDCAT! will give the entire protocol name. security_level door.sys wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char security_level[5] Description: String containing the users security level. See also user.sec below COMPATIBILITY Global Variables current_conference door.sys ------------------------------------------------------------------ Defined As: short current_conference; Description: Conference number user just exited from to door. caller_bday door.sys wildcat! ------------------------------------------------------------------ Defined As: char caller_bday[8]; Description: String containing the callers birthday. as MM/DD/YY. Not available with PCBoard systems. main_dir door.sys ------------------------------------------------------------------ Defined As: char main_dir[15]; Description: String containing the path to the MAIN directory wherever the users file is located. gen_dir door.sys ------------------------------------------------------------------ Defined As: char gen_dir[15]; Description: String containing the path to the GEN directory. sysop_name door.sys dorinfox.def ------------------------------------------------------------------ Defined As: char sysop_name[15]; Description: String containing the sysop's first name. sysop_alias door.sys ------------------------------------------------------------------ Defined As: char sysop_alias[15]; Description: String containing the sysop's alias name. ansi_NG door.sys ------------------------------------------------------------------ Defined As: short ansi_NG; Description: ANSI supported and caller using NG mode. TRUE/FALSE 0 = No, 1 = yes. record_lock door.sys ------------------------------------------------------------------ Defined As: short record_lock; Description: User record locking. TRUE/FALSE 0 = No, 1 = yes. default_color door.sys ------------------------------------------------------------------ Defined As: char default_color[2]; Description: String containing system's default color COMPATIBILITY Global Variables last_file_scan door.sys wildcat! ------------------------------------------------------------------ Defined As: char last_file_scan[9]; Description: String containing user last new files scan as MM/DD/YY. daily_files door.sys wildcat! ------------------------------------------------------------------ Defined As: char daily_files[4]; Description: String containing number of files user has download so far today. daily_bytes door.sys wildcat! ------------------------------------------------------------------ Defined As: char daily_bytes[4]; Description: String containing number of K bytes user downloaded so far today. total_doors door.sys ------------------------------------------------------------------ Defined As: char total_doors[4]; Description: String containing number of doors user has opened. msgs_left door.sys ------------------------------------------------------------------ Defined As: char msgs_left[4]; Description: String containing total number of messages left by user. max_files door.sys ------------------------------------------------------------------ Defined As: char max_files[4]; Description: String containing Max. number of files allowed. upload_Kbytes door.sys ------------------------------------------------------------------ Defined As: char upload_Kbyte[10]; Description: String containing total "K" bytes uploaded. download_Kbytes door.sys wildcat! ------------------------------------------------------------------ Defined As: char download_Kbyte[10]; Description: String containing total "K" bytes downloaded. dload_total door.sys wildcat! ------------------------------------------------------------------ Defined As: char dload_total[5]; Description: String containing total files downloaded. COMPATIBILITY Global Variables upload_total door.sys wildcat! ------------------------------------------------------------------ Defined As: char upload_total[5]; Description: String containing total files uploaded. monitor_type wildcat! ------------------------------------------------------------------ Defined As: char monitor_type[5]; Description: String containing monitor type MONO/COLOR NOTE: CKIT will set graphics true/false depending on this setting. see Graphics above. max_sec wildcat! ------------------------------------------------------------------ Defined As: char max_sec[5]; Description: String containing a systems maximum user security level for WILDCAT! systems. high_msg wildcat! ------------------------------------------------------------------ Defined As: char high_msg[10]' Description: String containing the users highest message read. name_in_use wildcat! ------------------------------------------------------------------ Defined As: BYTE name_in_use Description: Set to TRUE/FALSE. This is called already_connected in the WILDCAT def. file. door_opened wildcat! ------------------------------------------------------------------ Defined As: short door_opened Description: Which door was opened to run your door. BBSname dorinfox.def ------------------------------------------------------------------ Defined As: char BBSname[63]; Description: Name of the BBS system running the door. Global Variables These are part of the structure "user" as defined in the CKIT.H file. All these user structure members are available only if the door author specifies USERFILES True (see above) and the system is PCBoard version 14.x. Some but not all members are available if the author specifies USERFILE True and used with Pcboard version 12.0. If the door author does not specify USERFILE's file True and the door is using DOOR.SYS or CALLINFO.BBS some members of the structure are also available. Each member is marked whether if it is available with door.sys and/or PCBoard version 12.0. Also see update_user() below. user.name See also fullname PCBoard 12.0 ------------------------------------------------------------------ Defined As: char user.name[26]; Description: This C string is an ASCII string of the caller fullname as determined from user record. user.city door.sys PCBoard 12.0 Wildcat! dorinfox.def ------------------------------------------------------------------ Defined As: char user.city[25]; Description: This C string is an ASCII string of the caller city, state as determined from user record. user.pwrd door.sys and PCBoard ------------------------------------------------------------------ Defined As: char user.pwrd[13]; Description: This C string is an ASCII string of the caller password as determined from user record. user.bphone door.sys and PCBoard 12.0 ------------------------------------------------------------------ Defined As: char user.bphone[14]; Description: This C string is an ASCII string of the caller business phone number as determined from user record. user.phone door.sys and PCBoard 12.0 Wildcat! ------------------------------------------------------------------ Defined As: char user.phone[14]; Description: This C string is an ASCII string of the caller home phone number as determined from user record. user.last_date door.sys and PCBoard 12.0 ------------------------------------------------------------------ Defined As: char user.last_date[7]; Description: This C string is an ASCII string of the caller last date on system as determined from user record. Format is YYMMDD user.last_time door.sys and PCBoard 12.0 ------------------------------------------------------------------ Defined As: char user.last_time[6]; Description: This C string is an ASCII string of the caller last time on system as determined from user record. Format is HH:MM Global Variables These are part of the structure "user" as defined in the CKIT.H file. Information available from user file. user.expert See also expert above PCBoard 12.0 ------------------------------------------------------------------ Defined As: char user.expert[2]; Description: This C string is an ASCII string of the caller expert mode ( Y or N ) user.protocol door.sys and PCBoard 12.0 ------------------------------------------------------------------ Defined As: char user.protocol[2]; Description: This C string is an ASCII string of the caller protocol type in effect. user.filedate see also _last_file_scan ------------------------------------------------------------------ Defined As: char user.filedate[7]; Description: This C string is an ASCII string of the caller last DIR scan. in YYMMDD format user.security door.sys dorinfox.def ------------------------------------------------------------------ Defined As: BYTE user.security; Description: This variable holds the user security level as determined from USER file. user.total_calls ------------------------------------------------------------------ Defined As: short user.total_calls; Description: This variable holds the user total calls on system determined from USER file. user.page_length see also page_length door.sys ------------------------------------------------------------------ Defined As: BYTE user.page_length; Description: This variable holds the user page setting as determined from USER file. user.uploads see also upload_total ------------------------------------------------------------------ Defined As: long user.uploads; Description: This variable holds the user total uploads as determined from USER file. user.dloads see also dload_total ------------------------------------------------------------------ Defined As: long user.dloads; Description: This variable holds the user total downloads as determined from USER file. Global Variables These are part of the structure "user" as defined in the CKIT.H file. Information available from user file. user.comment1 door.sys ------------------------------------------------------------------ Defined As: char user.comment1[31]; Description: This C string is an ASCII string of the caller user maintained comment. user.comment2 ------------------------------------------------------------------ Defined As: char user.comment2[32]; Description: This C string is an ASCII string of the caller sysop maintained comment. user.expire_date door.sys ------------------------------------------------------------------ Defined As: char user.expire_date[7]; Description: This C string is an ASCII string of the caller expiration date in YYMMDD format. user.delete_user ------------------------------------------------------------------ Defined As: char user.delete_user[2]; Description: This C string is an ASCII string of delete user flag. (Y or N) user.time_used ------------------------------------------------------------------ Defined As: short user.time_used; Description: Elapsed time on system. (minutes) System Global Variables These variables are available with any system. Some are used for custiomization of your door program and MUST be defined. Others using are meant to be read only variables available globally. Some are are used in conjuction with high level functions as noted. char progname[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char prognam[21]; Description: Set this to your Door program name. It will be display on the status line on the sysop screen. MAXIMUM length is 20 characters! Do not exceed this! NOTE: THIS IS NOT AN OPTION. You must define progname[] even if you do not plan on using it. cmdline[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: BYTE cmdline[128] Description: This is used by get_cmdline(), to read the user keyboard input to. Please see the CKITDEMO.C for usage. See Also: get_cmdline(); par[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char par[128]; Description: This is used by get_nextpar(), to parse stacked commands to. Please see CKITDEMO.C for usage. See Also: get_cmdline(), get_nextpar(); scan_code pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: size_t scan_code; Description: This variable will if NONZERO contain the key_code of any NON-STANDARD keys on the IBM keyboard. (F1-F10, PgDn, PgUp etc). The remote user must be in some type of terminal program that will allow passing the keycodes. Qmodem in "DOORWAY" mode is one example. Please see input(), get_cmdline() and ckitdemo.c for examples. See Also: get_cmdline(); key_source pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: short key_source; Description: This variable will a 1 if the input from get_cmdline() came from the LOCAL console or a 2 if it came from a REMOTE console. See Also: get_cmdline(), input() System Global Variables system_time_HHMMSS[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char system_time_HHMMSS[9]; Description: This string will contain the current system time in the form HH:MM:SS and is available for general use. system_date_MMDDYY[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char todays_date_MMDDYY[9]; Description: This string will contain the current system date in the form MM:DD:YY and is available for general use. error_msg11[] pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: char error_msg11[40]; Description: Error message used by display_file. If you do not define this, CKIT will default to it's standard error message. MAX. 40 chars. (not including NULL). chatmode pcboard.sys door.sys wildcat! generic ------------------------------------------------------------------ Defined as: short chatmode; Description: This variable will a 1 (TRUE) if chat mode has been active. Use this to re-fresh your screen if needed. It is YOUR responsiblity to de-assert the variable after you have used it. (set to FALSE) Standard Data Types Standard Data Types CKIT defines a number of useful data types. BYTE ------------------------------------------------------------------- Defined As: typedef unsigned char BYTE; Description: The BYTE data type is useful in serial communications since it provides an easier and more logical way of handling 8 bit data from UART's used in serial communications. Functions Functions The CKIT Library contains a variety of functions. They are described as follows: Summary: Presents an exact syntactic model for each of the CKIT Library functions. Description: Describes a function's purpose and how it is used in an application program. Return Value: Explains any of the possible return values for a CKIT Library function. See Also: Lists any similar or related CKIT Library function. Example: Illustrates how a CKIT Library function could actually be used in an application program. Most function listed in the examples will be simply listed as function(). This may not indicate how they are called. To see how they are prototyped and called go to that function's page. I.E. If open_door is used in an example (other than it's own example) it may be simply refered to as open_door(). In reality open_door is really open_door(char * ...); The library functions are classified as 3 different types. High level, intermediate and low level. Normally a door would not need to make use of any of the functions except the high level functions. These handle and watch all the system timeouts, carrier detects, keyboard timeouts etc. If you need more control, there are other functions available. I will warn you. The lower level function you use, the less it will check for you automatically. Do not use these unless you have to. Functions open_door ------------------------------------------------------------------- Summary: #include "ckit.h" void open_door(); Description: The open door function initializes vectors, reads bbs system information. THIS MUST BE CALLED FIRST! The fist pointer should be be the path/name to the system file. The second pointer should be the path/name to the users file, if you designated USERSFILE=TRUE. (for pcboard systems only). As long as you have defined USERSFILE = FALSE, CKIT will not attempt to use the second pointer. Which ever you specify, the PORT:AAAA:A (if used) must be the last parameter passed to open_door();. Close_door MUST be called before exiting program after a call to open_door. See the CKITDEMO.C for more examples. Return Value: No value is returned. See Also: close_door. USERSFILE Example: This example assumes the path\filenames passed on the command line. i.e program_name path\filename path\filename port #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1], argv[2], argv[3]); <--- NOTE: display_info(); argv[2] and your_main_program(); argv[3] are close_door(); optional. exit(0); see below. } } NOTE: Both PORT and USERSFILE are optional. If a user needed to specify a non-standard port address and IRQ, then the syntax is PORT:AAAA:A where AAAA is the base address and A is the IRQ. It doesn't matter whether PORT:AAAA:A is the second or third parameter (depending on if you were opening the user file) passed to open_door() as long as it is the LAST parameter passed. Note also it does not matter which order on the cmd line the arguments are listed. The only thing that matters is which order they are passed to the open_door() function itself. You could also have the system path as part of a config file for your door. Then you would read your config file and pass the path read from it to open_door() as a string ptr. EXAMPLES: Assume door.cfg below is a config file that your door programs reads. This all depends on how or what is desired for your door program. You would need to document in your door documentation in what order the cmd line should be for your door program, read your config file and pass the system name\path to open_door(). Your program's cmd line: progname PORT:02F8:3 door.cfg open_door() call : open_door(system_path); <-string read from config file Your program's cmd line: program_name c:\pcb\pcboard.sys PORT:03F8:4 open_door() call : open_door(argv[1], argv[2]); Your program's cmd line: program_name \pcboard.sys PORT:03F8:4 \main\users open_door() call : open_door(argv[1], argv[3], arg[2]); Your program's cmd line: program_name c:\pcb\door.sys open_door() call : open_door(argv[1]); Your program's cmd line: program_name c:\wc\callinfo.bbs PORT:02F8:3 open_door() call : open_door(argv[1], argv[2]); Your program's cmd line: program_name c:\rbbs\dorinfo1.def open_door() call : open_door(argv[1]); Functions close_door high level ------------------------------------------------------------------- Summary: #include "ckit.h" void close_door(void); Description: The close door function resets vectors, closes files opened. THIS MUST BE CALLED LAST! Close_door MUST be called before exiting program after a call has been made to open_door. Not doing so will certainly lock you up. Return Value: No value is returned. See Also: open_door. Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . . your door program . . close_door(); }; }; Functions update_user PCBOARD 14.5 only high level ------------------------------------------------------------------- Summary: #include "ckit.h" void update_user(); Description: The update_user will accept a POINTER to the user structure member to update. See the user structure above. This function will only work for PCBoard 14.5 and USERSFILE must be set TRUE. CKIT will update the user file when the door is closed. If you do not want CKIT to update the user record after a change has been made set USERSFILE = FALSE before calling close_door(); Return Value: No value is returned. See Also: user structure Example: Change user security and comment1 field. MOTICE THE & BELOW!. You MUST pass the address of the member to update in the user structure. #include "ckit.h" main(int argc, char **argv) { USERSFILE = TRUE; static char new_comment[] = "ckit_user"; if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . user.security = 50; update_user(&user.security); strcpy(user.comment1, new_comment); update_user(&user.comment1); . . . close_door(); }; }; Functions s_puts high level ------------------------------------------------------------------- Summary: #include "ckit.h" void s_puts(char *); Description: The s_puts function displays a single NULL termintated (C string) to the local and remote console. It expects a pointer to the string of type BYTE or char to be displayed. It will not handle ANSI. See s_putstd() for ANSI and other usage. Return Value: No value is returned. See Also: s_printf, s_putv, s_putc, s_putsn, s_putstd Example: Two examples, both different useage of the string pointer. #include "ckit.h" static BYTE string[] = "This is a test"; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . s_puts(string); s_puts("This is also a test"); . . . close_door(); }; }; Functions s_putstd high level ------------------------------------------------------------------- Summary: #include "ckit.h" void s_putstd(char *); Description: The s_putstd function displays a single NULL termintated (C string) to the local and remote console. It expects a pointer to the string of type BYTE or char to be displayed. This function is identical to s_puts except it uses std output. This function should be used when ANSI code, or CTRL chars are needed to be sent to the local and remote consoles. Return Value: No value is returned. See Also: s_printf, s_putv, s_putc, s_putsn Example: Use s_putstd() to change background/foreground colors #include "ckit.h" #define cyanblue 0 #define yellowbrown 1 #define redgreen 2 #define redcyan 3 #define cyanred 4 #define cyanmagenta 5 #define bluegrey 6 static char *ansi_color[8] = { "\33[0;1;36;44mCyan on Blue\33[40m" "\33[44m\33[33;43mYellow on Brown\33[40m" "\33[43m\33[0;31;42mRed on Green\33[40m" "\33[42m\33[46mRed on Cyan\33[40m" "\33[46m\33[1;36;41mCyan on Red\33[40m" "\33[41m\33[45mCyan on Magenta\33[40m" "\33[45m\33[0;34;47mBlue on Grey\33[0m" }; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . s_putstd(ansi_color[cyanblue]); s_putstd(ansi_color[yellowbrown]); s_putstd(ansi_color[redgreen]); s_putstd(ansi_color[redcyan]); s_putstd(ansi_color[cyanred]); s_putstd(ansi_color[cyanmagenta]); s_putstd(ansi_color[bluegrey]); . . . close_door(); }; }; Functions s_putv high level ------------------------------------------------------------------- Summary: #include "ckit.h" void s_putv(); Description: The s_putv function displays a single NULL terminated (C string) to the local and remote console. It expects a variable argument of pointer(s) to the string(s) of type BYTE or char to be displayed. The list of pointers MUST end with a NULL pointer!. Not doing so will most likely either cause garbage to printed or even a hang-up. Return Value: No value is returned. See Also: s_printf, s_puts, s_putc, s_putsn Example: This example prints 2 strings with the pointer list terminated with a NULL pointer. #include "ckit.h" static BYTE string[] = "This is a test"; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . static BYTE string[] = "This is a test"; s_putv(string, "This is also a test", NULL); . . . close_door(); }; }; NOTE: an alternative to using s_putv would be to include the function below in your source code. You could use this function the same as you would printf(); This function has already been protyped in CKIT.H Functions s_printf high level ------------------------------------------------------------------- Summary: #include "ckit.h" void s_printf(char *,...); Description: The s_printf function is used to format an output to be sent to the local and remote console. It is exactly the same as the printf() function in C. To use it, you must include the source code listed below in your door program since s_printf() is NOT an actual part of the CKIT librarys. NOTE: if you want to send ANSI strings, change the s_puts in the s_printf function to s_putstd or create another std_printf function using s_putstd as the output. Return Value: No value is returned. See Also: s_printf, s_puts, s_putv INCLUDE THIS SOURCE CODE IN YOUR DOOR PROGRAM TO USE S_PRINTF! THE FUNCTION HAS ALREADY BEEN PROTOTYPED IN CKIT.H MODIFY AS YOU WANT. /**************************************************************************** * Printf() function for sending output to port * ****************************************************************************/ void s_printf(char *s_format,...) { va_list arg_pointer; char buffer[82]; /* default of 82 chars */ va_start(arg_pointer, s_format); vsprintf(buffer, s_format, arg_pointer); s_puts(buffer); va_end(arg_pointer); } Example: /**************************************************************************** * sending a string out the port using s_printf() * ****************************************************************************/ #include "ckit.h" short number 34; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . s_printf("Hello, %s. The number is %d.", firstname, number); . . . close_door(); }; }; Functions s_putsn high level ------------------------------------------------------------------- Summary: #include "ckit.h" void s_putsn(char *); Description: The s_putsn function displays a single NULL terminated (C string) to the local console only. It expects a pointer to the string of type BYTE or char to be displayed. Return Value: No value is returned. See Also: s_printf, s_putv, s_putc, s_putstd Example: Two examples, both different useage of the string pointer. #include "ckit.h" static BYTE string[] = "This is a test"; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . static BYTE string[] = "This is a test"; s_putsn(string); s_putsn("This is also a test"); . . . close_door(); }; }; Functions s_putc high level ------------------------------------------------------------------- Summary: #include "ckit.h" void s_putc(BYTE); Description: The s_putc function displays a single BYTE or char to the local and remote console. Return Value: No value is returned. See Also: s_printf, s_puts, s_putc. Example: This example prints a single BYTE (ASCII A) to local and remote console. #include "ckit.h" BYTE byte_to_send = 0x41; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ s_putc(byte_to_send); close_door(); }; }; Functions newline high level ------------------------------------------------------------------- Summary: #include "ckit.h" void newline(void); Description: The newline function sends a Carriage Return/ Line Feed to the local and remote console. Return Value: No value is returned. See Also: s_printf, s_puts, s_putc. Example: This example prints single CR/LF to local and remote console. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ . . . newline(); . . . close_door(); }; }; Functions clear_row high level ------------------------------------------------------------------- Summary: #include "ckit.h" void clear_row(short); Description: The clear_row function clears a given row on screen of the local and remote console. (row = 1 - 24). Used only if caller is in GRAPHICS mode. (ANSI) Return Value: No value is returned. See Also: clear_eol, clr_screen. Example: This example prints a string on a line, then erases the string. #include ckit.h char prompt1 = "Enter filename to view: "; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); /* pass system file(s) */ pos_cursor(10, 1); s_puts(prompt1); pos_cursor(11, 1); s_puts("Ready to clear above row, press a key"); while(!(wait_keypress())) { }; clear_row(10); /* clear row 10 */ newline(); close_door(); }; Functions clear_eol high level ------------------------------------------------------------------- Summary: #include "ckit.h" void clear_eol(void); Description: The clear_eol function clears to the end of line from current cursor position. Used only if caller is in GRAPHICS mode. (ANSI) Return Value: No value is returned. See Also: clear_eol, clr_screen. Example: This example clears to end of line on screen of local and remote console. #include ckit.h char prompt1 = "Enter filename to view: "; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); newline(); s_puts("Press a key to clear end of line below"); newline(); s_putv(prompt1, "\r", NULL); while(!(wait_keypress())) { }; clear_eol(); newline(); close_door(); }; }; Functions clr_screen high level ------------------------------------------------------------------- Summary: #include "ckit.h" void clr_screen(void); Description: The clr_screen function clears entire screen of local and remote console in either ASCII or ANSI mode. Return Value: No value is returned. See Also: clear_screen. Example: This example clears screen of local/remote console. #include ckit.h main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . clr_screen(); . . . close_door(); }; }; Functions clear_screen high level ------------------------------------------------------------------- Summary: #include "ckit.h" void clear_screen(void); Description: The clear_screen function clears entire screen of local console including status line. Return Value: No value is returned. See Also: clr_screen. Example: This example clears screen of local console. #include ckit.h main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . clear_screen(); . . . close_door(); }; }; Functions pos_cursor high level ------------------------------------------------------------------- Summary: #include "ckit.h" void pos_cursor(short, short); Description: The pos_cursor function positions cursor at row, column using ANSI (caller must be in GRAPHICS, if not no action will take place) row = 1 to 25, column = 1 to 80. CKIT will not let the local screen position cursor in status line area. Return Value: No value is returned. Example: This example positions cursor at row 10, column 15 on the local/remote consoles. #include "ckit.h" short row = 10; short column = 15; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . pos_cursor(row, column); . . . close_door(); }; }; Functions set_r_c high level ------------------------------------------------------------------- Summary: #include "ckit.h" void set_r_c(short, short); Description: The set_r_c function positions cursor at row, column BIOS on the local screen. row = 1 to 25, column = 1 to 80. Ckit will not let the cursor be placed in the status line area of local screen. Return Value: No value is returned. Example: This example positions cursor at row 5, column 1 on the local/remote consoles. #include "ckit.h" short row = 5; short column = 1; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . set_r_c(row, column); . . . close_door(); }; }; Functions back_space high level ------------------------------------------------------------------- Summary: #include "ckit.h" void back_space(short); Description: The back_space function backspaces cursor short number of spaces or to the 1st char in row, whichever is 1st. This is a destrutive backspace. Return Value: No value is returned. Example: This example backspaces cursor over the prompt and on the user's input local/remote consoles. #include ckit.h char prompt1 = "Enter filename to view: "; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); s_puts("\r\nReady to test back_space()"); s_puts("Press a key when ready"); newline(); while(!(wait_keypress())) { }; color(yellow); s_puts(prompt1); color(red); get_cmdline(); back_space(strlen(prompt1) + strlen(cmdline)); close_door(); }; Functions color high level ------------------------------------------------------------------- Summary: #include "ckit.h" void color(short); Description: The color function selects color to use using ANSI. Caller must be in graphics mode. If not, no action is taken. Return Value: No value is returned. See Also: Color macros above in macro section used with CKIT Example: This example sets color to red (see color macros above) on the local/remote consoles. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . color(blue); . . . close_door(); }; }; Functions get_cmdline high level ------------------------------------------------------------------- Summary: #include "ckit.h" void get_cmdline(void); Description: Read a line of input (max 128 bytes). Echo to screen, leave cursor after the last key typed before C/R. Automatically checks for time_left, carrier. Calls input() and reads into array cmdline*, automatically maps input to Uppercase. Will also set key_source to source of input. *defined in CKIT.H. This function is the one you would normally use for ALL user input. ALL other input functions are intermediate or low level functions. Return Value: No value is returned. See Also: input, get_nextpar, key_source, wait_keypress Example: This example reads keyboard from local/remote console into array get_cmdline[]. It also checks for any scan_codes receieved. See Ckitdemo.c also. #include "ckit.h" main(int argc, char **argv) { open_door(argv[1]); do { newline(); display_time(); color(green); s_puts("Command? "); get_cmdline(); /* read input into 'cmdline' */ } while((DUMP_USER != TRUE) && (strlen(cmdline) == 0) \ && (scan_code == 0)); } if (DUMP_USER == TRUE) { close_door(); exit(1); } if (scan_code != NULL) { color(white); read_scancode(); newline(); } if (get_nextpar()) { /* scan next parameter from cmdline into par */ newline(); /* process commands */ switch ( par[0] ) { case 'A': ansi_demo(); break; default: color(magenta); s_putv("(",par,") is not allowed! Try again:", NULL); *cmdline = NULL; } } Functions wait_keypress high level ------------------------------------------------------------------- Summary: #include "ckit.h" short wait_keypress(void); Description: Waits for any keypress. Does not wait for a C/R. Autochecks for CARRIER, TIMEOUTS etc. Returns ASCII code of key pressed or TRUE if DUMP_USER goes TRUE otherwise it will return FALSE. Will also return TRUE if extended key is pressed. Will not do so if a sysop function key is pressed. Useful for "hot_key" applications. Will also set key_source to proper value. Return Value: ASCII code of keypressed or TRUE, FALSE See also: check_CR, check_keypress, input, get_cmdline Example: This example will wait until a keypress or DUMP_USER. #include "ckit.h" prompt2 = ""Press any key to continue"; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . color(yellow); newline(); s_puts(prompt2); while(!(wait_keypress())) { }; back_space(strlen(prompt2) + 1); . . . close_door(); }; }; Functions force_enter high level ------------------------------------------------------------------- Summary: #include "ckit.h" void force_enter(void); Description: Prompts " Press Enter to continue: ", wait for C/R, automatic carrier, time_left and sysop checks. Return Value: NONE Example: This example displays a string then prompts and forces user to press C/R to continue. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . color(yellow); s_puts("Display this string\r\n"); force_enter(); . . . close_door(); }; }; Functions display_time high level ------------------------------------------------------------------- Summary: #include "ckit.h" void display_time(void); Description: Displays (xxxx used, xxx left) Return Value: NONE See Also: Example: See CKITDEMO.C also #include "ckit.h" main(int argc, char **argv) { open_door(argv[1]); if (argc > 0) { newline(); do { /* display_time_left; */ display_time(); color(green); s_puts("Command? ", NULL); get_cmdline(); /* read input into 'cmdline' */ newline(); } while( (DUMP_USER != TRUE) && ( strlen(cmdline) == 0 )); }; close_door(); }; Functions get_cmdline_raw high level ------------------------------------------------------------------- Summary: #include "ckit.h" void get_cmdline_raw(short); Description: Same as get_cmdline() above but erases prompt of after input and user input also. Expects length of prompt to be passed to it. Return Value: No value is returned. See Also: get_cmdline, get_nextpar, get_cmdline, input Example: This example reads keyboard from local/remote console into array cmdline[], (filename), then displays file. #include "ckit.h" char prompt1 = "Enter filename to display: "; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); s_puts(prompt1); get_cmdline_raw(strlen(prompt1)); newline(); display_file(cmdline); close_door(); }; }; Functions get_nextpar high level ------------------------------------------------------------------- Summary: #include "ckit.h" char get_nextpar(void); Description: Scans next from cmdline[] array into "par[]". par defined in CKIT.H Return Value: Returns 0 if none available, non-zero if cmd available See Also: input, get_cmdline, cmdline and par in GLOBAL section. Example: This example reads keyboard from local/remote console into array get_cmdline[], then calls get_nextpar to scan for cmds entered. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); do { get_cmdline(); /* read input into 'cmdline' */ } while( (DUMP_USER != TRUE) && ( strlen(cmdline) == 0 )); if (get_nextpar()) { /* scan next parameter from cmdline into par */ /* process commands */ switch ( par[0] ) { case 'A': ansi_demo(); break; default: break; }; }; }; close_door(); }; Functions nomore high level ------------------------------------------------------------------- Summary: #include "ckit.h" short nomore(void); Description: Displays prompt: "More: (Enter) or (Y)es, (N)o, (NS)nonstop? ". Returns 0 = Non_stop 1 = Yes 2 = No Also checks for CTRL K. The "More:" prompt will be yellow, the rest will be green. Return Value: short value, meaning described above/ See Also: get_def, get_defyn, get_defen Example: This example loops 3 times to show what each keypress (N,Y or NS) returns. #include "ckit.h" short result, i; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); for(i=0; i <= 2; i++) { s_puts("\r\nReady to test NOMORE 3 times"); newline(); while(!(wait_keypress())) { }; result = nomore(); printf("Nomore() returned %d", result); newline(); }; close_door(); }; Functions get_defyn high level ------------------------------------------------------------------- Summary: #include "ckit.h" void get_defyn(char *, short) Description: Displays prompt string and either "Enter=yes " or "Enter=no" based on short value. 1st prompt will be yellow, default will be green. If short is Non_zero it will display "Enter=Yes". If short is Zero (NULL) it will display "Enter=No". Calls get_cmdline for user input. Return Value: None See Also: cmd_line, get_def, get_defyn, get_defen Example: This example loops 2 times to show what each value or i displays. #include "ckit.h" short i; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); for(i=0; i <= 1; i++) { s_puts("\r\nReady to test get_defyn()"); newline(); get_defyn("Continue? ", i); s_putv("You entered ", cmdline, NULL); newline(); }; close_door(); }; Functions get_defen high level ------------------------------------------------------------------- Summary: #include "ckit.h" void get_defen(char *) Description: Same as get_defyn except the default string "(Enter=none?) " will be appended. 1st prompt will be yellow, default will be green. Calls get_cmdline for user input. Return Value: None See Also: cmd_line, get_def, get_defyn, get_defen #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); s_puts("\r\nReady to test get_defne()"); newline(); get_defne("Enter filename? "); s_putv("You entered ", cmdline, NULL); newline(); close_door(); }; Functions getdef high level ------------------------------------------------------------------- Summary: #include "ckit.h" void get_def(char *, char *) Description: Same as get_defen except both colored prompts are user defineable. The 1st prompt will be yellow, the 2nd one green. Calls get_cmdline for user input. Return Value: None See Also: cmd_line, get_def, get_defyn, get_defen Example: Print 2 prompts, and print user input. static char prompt1 = "Enter filename? " static char prompt2 = "(Enter = quit)"; #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); s_puts("\r\nReady to test get_def()"); newline(); get_def(prompt1, prompt2); s_putv("You entered ", cmdline, NULL); newline(); close_door(); }; Functions prompt_def high level ------------------------------------------------------------------- Summary: #include "ckit.h" void prompt_def(char *, char *) Description: Same as get_def except it does not call get_cmdline. 1st prompt will be yellow, 2nd prompt green. Return Value: None See Also: cmd_line, get_def, get_defyn, get_defen Example: Print 2 prompts. static char prompt1 = "Enter filename? " static char prompt2 = "(Enter = quit)"; #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); s_puts("\r\nReady to test prompt_def()"); newline(); prompt_def(prompt1, prompt2); get_cmdline(); newline(); close_door(); }; Functions getdefn high level ------------------------------------------------------------------- Summary: #include "ckit.h" void get_defn(char *, char *) Description: Same as get_def except appends "Enter=none" to end. Calls get_cmdline for user input. Return Value: None See Also: cmd_line, get_def, get_defyn, get_defen Functions dos_shell high level ------------------------------------------------------------------- Summary: #include "ckit.h" short dos_shell(char *); Description: Will shell to program pointed to by character string. If you plan on doing any shells, you need to use this function since it will disable the keyboard timer while the shell is taking place and perform some other clean up's upon re-entry. Return Value: Error level return by program called. NULL = NO error NOTE: For some reason Turbo C 2.0 does not return the error_level of the called program. TurboC++ does handle this properly. See also: F5 local shell to DOS, and CKITDEMO.C Example: Download a file using Zmodem. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . dos_shell("dsz sz pB4096 ckit.doc"); . . . close_door(); }; }; Functions display_file high level ------------------------------------------------------------------- Summary: #include "ckit.h" short display_file(char *); Description: Displays file to local/remote consoles. Automatic use of page_length, control K checks, MORE? prompting, closes file when done. Expects a pointer to name/path of file to display. If page_length is 0, the MORE? prompting will be disabled. You can use this to your advantage for files that you do not want MORE? prompting by setting user.page_length to 0 before calling display_file(). Just make sure you save the original value of user.page_length if you need it later on. This function will not automatically attempt to display a graphic file if the user is in graphics. For display non-interruptable menus, set page_length to NULL before calling this function. It is up to the door author to decide how he wants to handle it. see below. Return Value: Returns non-zero if error. If desired, you can then check the C global _errno for the cause of the problem. See Also: NONE Example: This example displays the file ckit.m, then forces user to press enter when done. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . strcpy(filename, "ckit.m") if(!graphics) { (display_file(filename); } else { strcat(filename,"g"); (display_file(filename); } force_enter(); . . . }; close_door(); }; Functions debug_on high level ------------------------------------------------------------------- Summary: #include "ckit.h" void debug_on(void); Description: A call to this function while debugging your door will disable the keyboard timer among other things while you are trying to debug your door. Make sure you remove this call before releasing your door or the keyboard timeout will not function! It should only be called after open_door();. This can also be used if needed to use transmit_modem() while the door is opened. This will disable DUMP_USER from going true. Make sure you turn debug back on! using debug_off(); Return Value: NONE Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . debug_on(); lower_dtr(); /* Drop user off */ raise_dtr(); ck_wait(1); /* wait for modem to reset */ flush_RQUEUE(); /* Flush receive queue */ transmit_modem("ATDT6159826537"); debug_off(); while(tqueue_len()); /* wait on modem */ newline(); delay(1); while(DUMP_USER != TRUE) { /* wait for modem */ get_cmdline(); newline(); s_putv("Modem returned -> ",cmdline, NULL); break; }; . . . }; close_door(); }; Functions debug_off high level ------------------------------------------------------------------- Summary: #include "ckit.h" void debug_on(void); Description: After a call to debug_on(), this will re-enable keyboard timer, etc. It should only be called after open_door(); Return Value: NONE Example: Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); debug_on(); /* while debugging door */ . . . }; debug_off(); close_door(); }; Functions input intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void input(BYTE *, short); Description: Read a line of input with specified length. Echo to screen, leave cursor after the last key typed before C/R. Automatically checks for time_left, carrier. Expects a char array pointer to store input and max. length of input to read. NOTE: Each call to input() will purge the buffer in use to NULLS. MAX length must not exceed the size of your array and it must not include the NULL char. (sizeof(array) - 1). It will also set key_source = 1 or 2. Return Value: No value is returned. See Also: get_cmdline(), inkey(), getkey(), key_source, wait_keypress() check_CTRL_K Example: This example reads keyboard input from local/remote console into array usr_input[] with max. bytes to read equal to 100 bytes. Will set key_source equal to source of input. NOTE: This a "intermediate" level function. You would not normally need to use this function. get_cmdline(); would normally be used and will handle all input for you. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . input(&usr_input[0], sizeof(usr_input) - 1); . . . close_door(); }; }; Functions check_time_left intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void check_time_left(void); Description: Checks time left on system, automatically sets DUMP_USER if time expired. Should be included in all major program loops if you are going to use it. Return Value: NONE See Also: display_time, get_cmdline Example: This function is normally handled by get_cmdline() and input(). You do not normally need to use it. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . check_time_left(); if(DUMP_USER == TRUE) { close_door(); }; . . . close_door(); }; }; Functions adjust_time_allowed intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void adjust_time_allowed(short); Description: Adjust user time left on system. Automatically updates PCBoard.sys to reflect change. This function will only be effective on systems using pcboard.sys. Return Value: NONE See Also: Example: For complete example see CKITDEMO.C included if (get_nextpar()) { /* scan next parameter from cmdline into par */ if (!strcmpi(thinking_of, par)) { color(green); s_puts("That's right! You get a 10 minute bonus!"); adjust_time_allowed(10); } else { color(blue); s_putv("Wrong! You lose 2 minutes! \ I was thinking of ", thinking_of,".",NULL); adjust_time_allowed(-2); } } Functions check_event intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short check_event(void); Description: Checks if time left will conflict with event. Return Value: 0 if no conflict, otherwise it will return the new minutes left before event. See Also: event_minutes, mins_before_event. EXAMPLE: CKIT will automatically check for event conflicts. This function would normally not be used. Functions event_minutes intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short event_minutes(void); Description: Checks minutes past midnight event is scheduled. This function is normally handled by CKIT. This function would normally not be used. Return Value: Number of minutes past midnight event is scheduled to run. See Also: check_event, mins_before_event. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . short event_mins; event_mins = event_minutes(); . . . close_door(); }; }; Functions mins_before_event intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short mins_before_event(void); Description: Check minutes left before event from current time. Return Value: Minutes before event from current time. See Also: check_event, event_minutes. Example: #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . short mins_before_event; mins_before_event = mins_before_event(); . . . close_door(); }; }; Functions delay intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void delay(short); Description: General purpose delay in milliseconds Minumum of 55 ms. (short must be >= 1) This function is good only on the MSC librarys. The TURBO librarys use Borland's DELAY() function. See also: ck_wait Return Value: NONE Functions ck_wait intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void ck_wait(short); Description: General purpose delay in seconds Minumum of 1 sec. for now (short must be >= 1) less than one will result in 1/2 second delay. Use delay above Return Value: NONE See also: Delay Functions purge_buffer intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void purge_buffer(BYTE *, short); Description: purge_buffer will purge any buffer to NULLS by passing a pointer to the buffer and the size of the buffer. i.e purge_buffer(buffer, 0x80). This may or may not be useful but is available. NOTE: There is a seperate purge function for the serial port input buffer if you wish to purge it before calling input. See flush_RQUEUE. Return Value: NONE See also: flush_RQUEUE static BYTE buff[256] = "This is purge buffer test"; #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . purge_buffer(buff, 255); . . . close_door(); }; }; Functions check_CR intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void short check_CR(void); Description: Check for a carriage return, does not wait, does not display any prompts. Returns TRUE or FALSE Return Value: TRUE, FALSE See also: force_enter(), get_cmdline(), check_keypress() Functions check_CTRL_K intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" short check_CTRL_K(void); Description: Check if a CONTROL K (ASCII 11) has been entered. Returns TRUE or FALSE Return Value: TRUE, FALSE See also: CtrlK_OFF, CtrlK_ON Functions CtrlK_ON intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void CtrlK_ON(void); Description: Enables CONTROL K (ASCII 11) checking. This is normally off since most menu types are non_interruptable. If turned on, CTRL K will be recognized. Once on, you must call CtrlK_OFF() (see below) to disable it. CTRL K's are also NOT put into the input buffer. You have to use the check_CTRL_K() function (see above) to determine if a CTRL K has been pressed. See also: CtrlK_OFF, check_CTRL_K() Functions CtrlK_OFF intermediate level ------------------------------------------------------------------- Summary: #include "ckit.h" void CtrlK_OFF(void); Description: Disables CONTROL K (ASCII 11) checking. See also: CtrlK_ON, check_CTRL_K() Functions NOTE: ALL the low level functions below are not normally needed and are handled automatically by CKIT in a higher level function. Most of these functions do NO carrier detects, etc. They are only provided in special cases that may need them. Use with caution. inkey low level ------------------------------------------------------------------- Summary: #include "ckit.h" size_t inkey(void); Description: Read character (if available) from local/remote console. Does not wait for input. Also sets key_source equal to SYSOP or USER_KEY Return Value: Returns 0 if none available, otherwise returns key pressed See Also: input, sio_getbyte, key_source above in globals, check_CTRL_K Example: This example checks for A at the keyboard, from local/remote console, returns TRUE or FALSE #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . if ( inkey() != 'A') { return(FALSE); } else { return(TRUE); } . . . close_door(); }; }; Functions keystat low level ------------------------------------------------------------------- Summary: #include "ckit.h" short keystat(void); Description: Check if character is available from local console. Does not wait for input. Return Value: Returns 0 if none available. None-zero is available. See Also: input, r_count, key_source above in globals, Example: This example checks for keypress at the keyboard local console, returns TRUE or FALSE #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . if ( keystat() ) { return(FALSE); } else { return(TRUE); } . . . close_door(); }; }; Functions r_count low level ------------------------------------------------------------------- Summary: #include "ckit.h" short r_count(void); Description: Check if character is available from remote console. Does not wait for input. Return Value: Returns NULL if none available else returns number of characters in the recieve queue. See Also: input, r_count, keystat. Example: See flush_rqueue below Functions getkey low level ------------------------------------------------------------------- Summary: #include "ckit.h" size_t getkey(void); Description: Read character (if available) from local console. Does not wait for input. Return Value: Returns FALSE if none available. Zero if true. See Also: input, getkey, keystat, check_CTRL_K Example: This example read key from local console buffer and print to screen. #include "ckit.h" size_t ch; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . ch = getkey(); s_putc(ch); . . . close_door(); }; }; Functions sio_getbyte low level ------------------------------------------------------------------- Summary: #include "ckit.h" BYTE sio_getbyte(void); Description: Read character (if available) from remote console. Does not wait for input. Return Value: Returns NULL if none available else returns character read. See Also: input, sio_getbyte, keystat, check_CTRL_K Example: This example reads byte from remote console buffer and displays it, if one was available. #include "ckit.h" BYTE ch; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . ch = sio_getbyte(); if(ch) { s_putc(ch); }; . . . close_door(); }; }; lower_dtr low level ------------------------------------------------------------------- Summary: #include "ckit.h" void lower_dtr(void); Description: Drops DTR on com port, causing modem to hang up. Return Value: NONE See Also: raise_dtr, transmit_modem, transmit_data Example: see transmit_modem below Functions raise_dtr low level ------------------------------------------------------------------- Summary: #include "ckit.h" void raise_dtr(void); Description: Raises DTR on com port, causing modem to hang up. Return Value: NONE See Also: lower_dtr, transmit_modem, transmit_data Example: see transmit_modem below Functions force_offhook low level ------------------------------------------------------------------- Summary: #include "ckit.h" void force_offhook(void); Description: Drops DTR on com port, causing modem to hang up, tells modem to go back offhook. This function will wait 1 second after dropping dtr and 2 seconds after raising DTR before telling modem to go offhook. This is normally handled automatically by CKIT depeding on the FORCEOFFHOOK setting. Return Value: NONE See Also: FORCEOFFHOOK above. Example: Send a string to reset the modem if carrier is lost. #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . force_offhook(); /* Dump user offline */ . . . }; close_door(); }; Functions transmit_data low level ------------------------------------------------------------------- Summary: #include "ckit.h" void transmit_data(BYTE *); Description: Send C string to remote console. No echo to local console. Expects a pointer to either a NULL terminate C string of type BYTE or char. Check for carrier included. Return Value: NONE See Also: transmit_modem Example: #include "ckit.h" static char remote_msg[] = "HELLO"; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . transmit_data(remote_msg); . . . }; close_door(); }; transmit_modem low level ------------------------------------------------------------------- Summary: #include "ckit.h" short transmit_modem(BYTE *); Description: Send C string to modem/remote. No echo to local console. Expects a pointer to either a NULL terminate C string of type BYTE or char. NO carrier checking is included. If it returns Non-Zero if error occured, otherwise it returns NULL. Return Value: NONE See Also: transmit_data Example: #include "ckit.h" static char dialnumber[] = "ATDT6159707418"; #include "ckit.h" main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . debug_on(); lower_dtr(); /* Drop user off */ raise_dtr(); ck_wait(1); /* wait for modem to reset */ flush_RQUEUE(); /* Flush receive queue */ transmit_modem(dialnumber); debug_off(); while(tqueue_len()); /* wait on modem */ get_cmdline(); strcmp(cmdline, "CARRIER"); . . . }; close_door(); }; Functions tqueue_len low level ------------------------------------------------------------------- Summary: #include "ckit.h" short tqueue_len(void); Description: Check number of bytes left in Transmit RQUEUE. Normally this routine is not needed but is available if needed. Return Value: Bytes left in XMIT QUEUE See Also: Example: #include "ckit.h" static char modem_msg[] = "ATX4"; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . debug_on(); transmit_modem(message); while(tqueue_len()); debug_off(); . . . }; close_door(); }; Functions flush_RQUEUE low level ------------------------------------------------------------------- Summary: #include "ckit.h" void flush_RQUEUE(void); Description: Flush bytes from Receive QUEUE buffer. Return Value: NONE See Also: r_count, tqueue_len Example: #include "ckit.h" static char message[] = "ATH1"; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . flush_RQUEUE(); /* flush buffer */ transmit_modem(message); while (r_count()); /* wait for response back */ . . . }; close_door(); }; Functions check_cd low level ------------------------------------------------------------------- Summary: #include "ckit.h" BYTE check_CD(void); Description: Checks if carrier present. If present, returns NON-zero. Zero (NULL) means no carrier present. Return Value: BYTE indicator of carrier present/ See Also: DUMP_USER, transmit_data, transmit_modem Functions check_keypress low level ------------------------------------------------------------------- Summary: #include "ckit.h" short check_keypress(BYTE); Description: Check for any specific ASCII character entered. Does not wait for a character. This function may or may not be useful but is available if needed for a "hot_key" function in a door. Does no carrier checking! Return Value: TRUE, FALSE See also: check_CR, input(), getkey(), wait_keypress, check_CTRL_K Example: #include "ckit.h" BYTE result; main(int argc, char **argv) { if (argc > 0) { open_door(argv[1]); . . . while { !(result = check_keypress(0x41)); }; printf("Keypress returned %d", result); . . . }; close_door(); }; CKIT based DOOR programs have many of the feature available for the door author, and for the sysop using standard function keys such as: Function key ------------ F5 Shell to DOS F8 Return user to system F9 Toggle display on/off F10 Chat mode (use the ESCAPE key to exit) * F3 Toggle printer on/off * F4 Toggle pagebell on/off * F7 Toggle caller alarm on/off Alternate key ------------- ALT-H Toggle between different status lines * ALT-N Toggle sysop on next * ALT-X Toggle exit to dos after call and help lines Alternately pressing the ALT-H key will bring up the next status line screen. The 1st screen is a help screen, the second second screen shows your COM port status. * The function keys marked with an "*" will only be of use to systems using pcboard.sys. The rest are functional with any system. Command stacking is also available and can be easily disabled if desired. See the CKITDEMO.C for example of disabling command stacking. Files ------- CKIT.DOC - This file. CKITDEMO.EXE - This is a very short program written to test CKIT libraries and for a short demo. CKITDEMO.EXE is a compiled program using the CKIT library. CKIT.H - This is a standard C header file, to be included with your door program. This file contains all the function prototypes, and variable names and types available from CKIT. CKIT_MS.LIB - This file is the CKIT library file to access all of the CKIT CKIT_MM.LIB files that are linked into your door program for MSC. CKIT_TS.LIB - This file is the CKIT library file to access all of the CKIT CKIT_TM.LIB files that are linked into your door program for TURBO C. CKITDEMO.C - The source code for CKITDEMO demostrating a door written using CKIT functions. DEMO.BAT - Sample .bat file to compile and link using the CKIT.LIB Provided as an example. CKIT_TC.ZIP - Contains TURBO C files TCREAD.ME - Information for TURBO C users CKITDEMO.MAK - TURBO C Make file for CKITDEMO door (for use as example)* CKITS.PRJ - TURBO C Project file for CKITDEMO door (use as example)* TCPPCKIT.PRJ - TURBO C++ Project file for CKITDEMO door (use as example)* * For small models ATTENTION TURBO C USERS: You must select WORD alignment when using functions from the TURBO librarys. The default on BORLAND is BYTE alignment. This will not work correctly. See the file TCREAD.ME in the CKIT_TC.ZIP file. In addition, TURBO C++ users should also select standard stack frame alignment. Make a dir to work from. Copy the CKITDEMO.C, CKITDEMO.H, CKIT.H, the CKIT_T?.LIB's, and the TCPPCKIT.PRJ or CKITS.PRJ into the same dir. Bring up the TURBO C IDE and select the proper project file and you can test the CKITDEMO.C. Have it create an .exe file. This should get you started. You can take it from here... This package can be freely distributed so long as it is not modified or sold for profit. If you find that this program is valuable, you can send me a donation for what you think it is worth. I suggest at least $25.00 (USA exchange). You will receive a program CKITREG.EXE. This will register all future copies of CKIT with your registration number. This means you would only have to download the new versions from your favorite board, saving you long distance charges! For registration over $25.00, full access to all Nodes on Data-Comp will be made available. Send your contributions to: Rickie W. Belitz P.O. Box 5895 Maryville, TN 37802-5895 SUPPORT ----------- If you have any questions, suggestions, or bug reports, contact me at: Data-Comp BBS (615) 982-8723 (Hayes Ultra V.32) (public line) (615) 982-6537 (Hayes Ultra V.32) (private line) (615) 982-6512 (USR HST Dual Standard V.32), (private line) (615) 970-7418 (USR HST Dual Standard V.32), (private line) NOTE: The board has automatic rollover on the phone lines. There is chance you could end up on one of the private lines with limited time. I can also be reached via mail networks thru INTELEC's SHAREWARE conference and Relaynet's DOORS conference. ACKNOWLEDGEMENTS -------------------- I would like to give special thanks to my Co-sysop, Dean McGuire, who has patiently tested the door routines and for help preparing the documentation. GENERIC.SYS -------------------------- For maximum compatibility, CKIT will also read a file called GENERIC.SYS. This file can be created by the sysop desiring to run the door and allow CKIT to operate. This would allow your door to operate on ANY BBS system. (see compatibilty issues below). The GENERIC.SYS file is a standard ASCII file and contains 3 lines, each followed by a carriage return, line feed. The format is: line 1 - The BBS operator's name. line 2 - The COM port in use. line 3 - Time allowed in door. When CKIT finds a GENERIC.SYS, it will ask the user for his/her first and last names before opening the door. After the user inputs their name, the door will continue to load and run. Below is an example GENERIC.SYS file with a sysop name of Rickie, using Com port 1, and allowing 50 minutes in the door. Rickie COM1: 50 Each line is followed by a C/R, L/F and the com port follows the same format as the standard door.sys. COM0: = Local Mode (same as door.sys) See the compatibilty issues below for more information. COMPATIBILITY ISSUES -------------------------- Although CKIT makes a lot information available to the user, the author has to decide on what particular information his or her door will require. Here are some general guidelines that may help. Decide on exactly what information your door will need to operate. Keeping this to a minimum increases your chances of maintaining compatibility thruout the different BBS's systems and versions thereof which CKIT supports. For example, let's assume you are designing a standard BBS game. CKIT handles all the detailed information such as time left, carrier detect etc. All you would really need is some basic information. Perhaps just the user's name and sysop name. By keeping this type of information to the minimum, your door would work regardless of whether the sysop running your door used pcboard.sys, door.sys, callinfo.bbs or GENERIC.SYS on the command line..i.e, game.exe c:\pcb\pcboard.sys OR game.exe c:\pcb\door.sys OR game.exe c:\wc\callinfo.bbs, OR game.exe c:\GENERIC.SYS OR game.exe c:\rbbs\DORINFOx.DEF;, ANY of these would work. (If the sysop was running PCBoard 12.0, he would only be able to use pcboard.sys. In this case, CKIT would not only take care of deciding if it was a pcboard.sys file, door.sys file, WILDCAT! callinfo.bbs or DORINFOx.DEF, but also if it *is* a pcboard.sys file, whether it is a PCBoard 12.0 sys file or later, and then would read it properly!). This would make your door compatible with the full spectrum of PCBoard 12.0-14.5, WILDCAT!, GAP, SPITFIRE 3.0, other systems using the standard door.sys file, RBBS and others using DORINFO1.DEF and ANY BBS using GENERIC.SYS with minimum effort on the part of the sysop running your door. Once you've written this fantastic new door, if it's a snap for a Sysop to install it, this might make him a bit more inclined to register it, right? Another senario would be if your door needs somewhat more than the basic information. I would recommend using the variables available in door.sys and WILDCAT! info file in this case. This would give you the broadest coverage for your door. If you will notice in the variables descriptions in this manual, there is a compatibility list to the right of each variable. This tells you which and what type of information is available to you depending on whether your door found a door.sys, pcboard.sys (and which version of PCBoard), WILDCAT! info file and DORINFOx.DEF file. Below is a summary and quick guide to each pcboard.sys version, door.sys, WILDCAT!, DORINFOx.DEF info file and which information variables are available with each. If you need EVEN more information, then you can tell CKIT to open the users file and read information. Doing so will limit your door to PCBoard systems only. CKIT will NOT record any information to the user's file. It is a read only function. You may also want to record new information to the users file. CKIT has the capability of doing so and if you need this, contact me and we can work something out. This is mainly for safety reasons. Compatible with... ---------------------------------------------------------- PCBoard.sys Variable 12.0 14.0-14.5 DOOR.SYS WILDCAT! DORINFOx.DEF GENERIC.SYS -------------- ---- -------- -------- ------- ----------- ----------- *conferences X X aport X X X X X X ansi_NG X BBSname X bps_open X X X baud_rate X X X X X callalarm X X X current_conference X X X caller_bday X X display X X X X X default_color X daily_bytes X X daily_files X X download_Kbytes X X door_opened X dload_total X X X error_connection X X X X expert X X X X event_active X event_time X X X firstname X X X X X X fullname X X X X X X graphics X X X X X gen_dir X high_msg X key_source X X X X X local X X X X X logoff_color X X X X exit_msg X X X X X language X X last_file_scan X X X X min_left X X X X X X main_dir X max_files X max_sec X monitor_type X msgs_left X name_in_use X netchat X X node X X X X printer X X X protocol X X X X pagebell X X X password X X X X page_length X X X X X PCB X X X X X PCB12 X X X X X prev_used X port X X X X X parity X X RBBS X X X X X X record_lock X scan_code X X X X X security_level X X X slide_event X sysop_next X X sysop_name X X X sysop_alias X time_logged X X X X X time_on X X time_limit X X time_added X X total_doors X user_record X X X X upload_Kbytes X upload_total X X X user.city X X X X X user.comment1 X X user.expire_date X X user.phone X X X WILDCAT X X X X X One last note - There are three variables PCB12, PCB and WILDCAT. When CKIT reads a pcboard.sys file, it will set the PCB variable TRUE. If the pcboard.sys file it read was a 12.0 file, it will set the PCB12 variable true. If CKIT finds a WILDCAT system, it will set the variable WILDCAT true. This may be useful in making adjustments to your program depending on which system file was read (PCB, DOOR.SYS, PCB12, WILDCAT) and/or if a sysop was running PCBoard 12.0 and you normally expected door.sys or wildcat info file. Also, see the users file information earlier in the doc file. Some of the users structure information is available even if you are just using door.sys. If you do tell CKIT to open the users file, all the users file information above will be available, if CKIT finds a version 14.x pcboard.sys. If it finds a PCBoard 12.0 pcboard.sys file, some, but not all, of the users structure information will be available. Each member of the users structure is marked to indicate what is available and what is not depending on the things just mentioned. Warranty Warranty ------------ I make no warranty of any kind, express or implied, including without limitation, any warranties of merchantability and/or fitness for a particular purpose. I shall not be held liable for any damages, whether direct, indirect, special or consequential arising from a failure of this program to operate in the manner desired by the user. I shall not be held liable for any damage to data or property which may be caused directly or indirectly by the use of this program. In no event will I be held liable for any damages, including (but not limited to) any lost profits, lost savings or other incidental or consequential damages arising out of the use or inability to use this program, or for any claim by any other party. This warranty is governed by the laws of the State of Tennessee. ORDER.FRM ------------- Return to: Rickie Belitz P.O. Box 5895 Maryville, TN 37802-5895 Name ______________________________________________________________ Company ___________________________________________________________ Address ___________________________________________________________ ___________________________________________________________ Phone _____________________________________________________________ Register CKIT to: Name____________________________________________ Diskette size: ____ 5.25" acceptable ____ 3.5" required* Canadian residents add $4.00 (current exchange rate) _________ *Add $4.00 for 3.5" diskettes 720K ___ 1.44 ___ _________ Please find enclosed a check or money order for USA $_________ ($25.00 suggested) payable to Rickie Belitz. This shows my support of Shareware products and the Shareware concept. It also shows my encouragement to help further development of CKIT. I understand that CKIT is provided as-is and no warranties of any kind, expressed or otherwise, are included and that I am using it at my own risk. Signed: _________________________________________ Date: _________ RELEASE HISTORY ------------------- 01-May-90 v1.0 Initial BETA testing as CKIT10ß.ZIP Beta 1.0 release. The next release of CKIT, I predict, should have about a 15% to 20% reduction in code size. If you find any problems with CKIT, please contact me at the phone numbers/address above. 01-Jun-90 v1.0 Release of version 1.0 13-Jun-90 v1.0 Release of version 1.0A Added library support for TURBO C. Added wait function. Minor documention fixes. 16-Jun-90 v1.0 Release of version 1.0B Fixed a minor error in the TURBOC small library. I had left a INCLUDELIB in the code by mistake and you were forced to use the /N Tlink switch. This has been corrected and the use of /n is no longer needed. 20-Jun-90 v1.0 Release of version 1.0C Fixed another minor problem where the assembler I used had converted all my functions to uppercase in the .obj file. I thought the default was to not do that but as it turns out it wasn't. Now all the library function names/variables are the right case. 25-Jun-90 v1.05 Release of version 1.05 Added support for 16550AN UART. The code will take advantage of 16550AN chip if present. Added caller log function. Begin including the medium library with Zip. This was done because of the self-registering feature. Took out time limit that CKIT originally had. Future releases will not have any limitations. 25-Jul-90 v1.1 Release of version 1.1 This release was a little premature. I went ahead and released it since it did fix a couple of problems. * indicates a new feature. Display_file() - a. It will now put a space before the filename when it reports a problem. b. The EOF is no longer displayed. c. display_file() will now correctly display text files that have ANSI codes embedded in the file. d. CTRL-K now works on the local keyboard. (The remote keyboard was OK) * e. display_file() will now return TRUE/FALSE to indicate whether a problem had occured. You can then check the C global variable _errno for cause of error. * f. Fixed problem when user.page_length was equal to 0. See the CKIT.DOC for hints on how to take advantage of this feature. 2. display_time() - Would not update to the time used until after two carriage returns were entered. fixed 3. input() a. Control characters or any non-displayable characters below 1F hex will not increase the counter. This corrects the problem of being able to backspace too far and erasing the prompts. * b. Each call to input() now will purge the buffer into which you wish to place keyboard input. You should no longer have to include the statement memset(buffer, 0, 21) before calling input(). * c. A new function purge_buffer will purge any buffer to NULLS by passing a pointer to the buffer and the size of the buffer. i.e purge_buffer(buffer, 0x80). This may or may not be useful but is available. NOTE: There is a separate purge function for the serial port input buffer if you wish to purge it before calling input. See CKIT.DOC * d. New function available called check_keypress. Checks for any specific ASCII character. This function will return TRUE/FALSE as defined in CKIT.DOC. * e. Another new function called check_CR will check for a carriage return and return TRUE/FALSE. 4. get_nextpar() - Would only accept 2 stacked commands, fixed. While working on the get_nextpar() function, I went ahead and targeted it for some optimization along with the get_cmdline() function. The results are: get_nextpar() is now smaller and 7% faster. get_cmdline() is now smaller and 45% faster. Overall, with all the corrections and added functions the .obj file for CKIT is now 2% SMALLER than before. 11-Aug-90 v1.5 Release of version 1.5 Ckit is now compatible with PCBoard version 12.0, 14.x-14.5, GAP BBS, and other BBS systems using the standard door.sys file. The level of compatiblity is up to the door author and the type of information needed. There is a lot of information available, but by keeping this to a minimum, the door author can write his door to be compatible with all the systems above with no extra instructions to the user of the door except for the PCBoard sysop to use either pcboard.sys or door.sys. (Version 12.0 would have to use pcboard.sys and all others use door.sys.) CKIT will automatically determine which file to read and which PCBoard version is in use. See the compatiblity section in this doc file for more information and a Variables Quick-Reference. Added more features and cosmetics to the program's status line for the sysop's use... F8 - Return user to BBS. This was always there, I just forgot to document it. :) F5 - Shell to DOS ALT-X - Sets the PCBoard's exit to DOS after caller flag ALT-N - Sets the PCBoard's sysop on next after caller flag ALT-H - Display Help Screen on sysop status line, and next ALT-H will show com port status Functions added are: dos_shell(char *) - Allow door author to shell to another program for execution if desired. See CKIT.DOC _debug_on(void); - Turns off keyboard timer and other things while door author is debugging his door. Additional variables: short PCB12, expert, parity, *conferences, current_conference, caller_bday[8], main_dir[15], gen_dir[15], sysop_name[15], sysop_alias[15], page_length, ansi_ng, default_color[2], last_dir_scan[8], daily_files[4], total_doors[4], msgs_left[4], max_files[4], upload_Kbytes[10], download_Kbytes[10], dload_total[5], upload_total[5] - Added my own math routine so you no longer have to include MATH.LIB if you are using TC compiler. - Reduction of code size by about 20% relative. 13-Aug-90 v1.5A Release of version 1.5A I can't believe I did this. After telling everyone to make sure and not have debug_on in the released versions of their door, I released CKIT with debug on!. As a result, the keyboard timer and some other things would not work properly. This release with a code date 8/13/90 will work properly. 19-Aug-90 v1.6 Release of version 1.6 - Added support for WILDCAT! systems. The following additonal information is available for WILDCAT! users. Additional WILDCAT! variables: monitor_type[5], max_sec[5], high_msg[5], door_opened[5], BYTE name_in_user - Additional variables for general use by any system: short WILDCAT, protocol[15], security_level[5] See the CKIT.DOC for explanations and the compatibility chart. - clr_screen() was not properly handling NON_ANSI callers. fixed - progname[] was changed to progname[21]. Previously it was [20] - Under certain circumstances, a parsing routine in CKIT could get hung up. fixed. - Reduction of code size by about 5% relative. - Fixed some documentation errors. In particular, you may want to reprint the open_door() page and progname variable page. Also there are new variables listed above in the doc file and the compatibility chart has been upgraded. - Look over the NEW CKITDEMO.C and CKITDEMO.H files. The demo demostrates some use of added features, (zmodem download, pcb, wildcat! etc). 01-Sep-90 v1.7 Release of version 1.7 - Added support for reading scan codes from non-standard keys on IBM keyboards. (F1-F10, Arrows, PgUp, PgDn, etc). - Ability to define the logoff message and color - Ability to change the port address and IRQ if needed. PORT:AAAA:A where AAAA equal to port base address and A is IRQ i.e PORT:02F8:3 would be the same as COM2. - Additonal variables: short scan_code, short logoff_color, char exit_msg[40] - Additonal functions: short wait_keypress(void) for "hot_keys". - open_door()'s prototype has been changed. This allows one to pass as many parameters as desired (up to the max. of 3), without having to pass any dummy pointers. - Fixed a problem in the cmd line where certain command line parameters (callinfo.bbs and pcboard.sys) passed were case sensitive. This caused CKIT to read them incorrectly. - Cleaned up the status line display when certain information was not available depending on which file was opened. (pcboard, door.sys, callinfo) - Additional documentation added and improvements. Classified functions into groups. Once again, see open_door() for some changes and key_source. The option variable documention has also been updated. Also see the ckitdemo.c for more examples. 16-Sep-90 v1.71 Release of version 1.71 This release was intended to be a maintenance release. There were, however, a few things added and a couple items repaired. - Added a function to re-enable keyboard timer after it had been turned off by a previous call to debug_on(). The new function name is debug_off(). - Added the ability to define your own error message for the display_file() function. error_msg11[40]. If you don't define it, CKIT will use it's default. - More and more and more documentation updates and examples. Too many additions to list here. Mostly more examples and better explanations. - Fixed the display_file() function so that it will properly handle files that did not contain line feeds. There will also be a future release of display_file() that will handle the ANSI screens better and include PCB color macros. - Close door was clearing the screen when exiting. It no longer does this. - Fixed the More: (Y)es, (N), (NS)non-stop prompt. Somehow in the last release, the last part of the string was missing from the source code. - Also missing in the last release source code was the public declares for transmit_modem, set_r_c and another function. Not sure how this happened but it did. Your linker will now find these. - The page_length should be accurate now. The bug that was in PCBoard's 14.5 door.sys has been fixed and I changed CKIT to give the true page length. 12-Nov-90 v1.75 - Added a function to update user record IF you are writing the door for use with PCBoard 14.5. The new function name is update_user(). - Added the ability to turn on and off Control K checking, if desired. This involves the additon of 3 functions. CtrlK_ON, CtrlK_OFF, and check_CTRL_K. - Added chat mode via function key 10. Also a variable short chatmode is set to TRUE when chat mode has taken place. - CKIT will now read a file called GENERIC.SYS. This file will allow the door to work on ANY BBS system, depending on the level of information required for door. - Added some enhancements to the status line for the COM port status. It will now display the status of CTS, DTR, DSR and DCD. - Fixed a problem with ALL the medium models. Also fixed a problem with the delay() function in the MSC libraries. There is also a large memory model now available for registered users. 24-Nov-90 v1.75A - Fixed a problem in the last release for sysops using the pcboard.sys file. CKIT would always report "Time adjusted for upcoming event". 15-Feb-91 v1.75C - Not sure what happend 1.75B but anyway, the C version fixed a few loose ends. - Fixed code so that door.sys, wildcat, and generic.sys files are closed after a call to open_door(). - Changed so that if sysop is logged on, (using pcboard.sys), the firstname will be set to what is in the pcboard.sys file instead of "sysop". - Added a pointer to the internal buffer that pcboard.sys is held and which will be used to update pcboard.sys when returning to the board. Added pointer to internal pcboard.sys buffer - BYTE *pcbsysbuf - Changed logoff_msg[] to exit_msg[]. logoff_msg[] is now displayed if the user says good-bye within the door. See CKIT.H for the macros LOGOFF and EXITDOOR. The complete log-off routines and source code for reading pcboard.dat files are on Data-Comp BBS. These can be linked with CKIT if you want to add a log-off feature for PCBoard doors. 24-Mar-91 v1.76 - Added support for RBBS-PC and other systems using the DORINFOx.DEF system files. - Source code for reading PCBoard data files are available on Data-Comp BBS and may be linked with your C door program if desired. RBBS and and others will be as they become available. 05-Apr-91 v1.76A and 1.76B - Added s_printf() function. This will allow you to format your output the same as you would use printf(). You must include the source code in the CKIT.DOC to use it. See the CKITDEMO.C and CKIT.H. This function is not really part of the ckit libraries so you must include the source code for s_printf() in your program. The source can be found in the docs under s_printf or the CKIT.H file. - Fixed a problem with input(). If the user tried to exceed the maximum length of your input buffer CKIT would display some garbage chars. 06-Apr-91 v1.76C - Fixing the input() problem created another problem whereas CKIT would not display the exit_msg when returning to the BBS. Fixed. SOME COMMON PROBLEMS/QUESTIONS ------------------------------ Q. When linking my code with the library I get a linker error - Unresolved external _progname in CKIT3.ASM. A. CKIT will look for a C string array called progname[21];. This the name of your door program and will appear at the bottom of the local line. This is not an option. You must declare some kind of name for CKIT to use even if it just a space char if you don't want your progname at the bottom. See the CKIDEMO.H file for example and the variable progname[] in the doc file. Q. When linking your ckitdemo program, I get an error - Unresolved external _random in ckitdemo.c A. The Ckitdemo.c door was written to be compiled with either Microsoft C or Turbo C. As such, there are compiler directives in the CKITDEMO.C file that will take appropriate action depending on the compiler. Therefore, when compiling the CKITDEMO.C program, you must have the statement -DCOMPILER=MICROSOFT or -DCOMPILER=TURBOC on the command line. This is needed only when compiling the CKITDEMO.C program. It is NOT needed when you are compiling your own door program. Q. Do I have to include the -DCOMPILER-MICROSOFT or -DCOMPILER=TURBOC on the command line every time I compile my door program? A. No, this was only needed for the CKITDEMO.C source code. You can also modify the ckitdemo.c and ckitdemo.h file and take the compiler directives out if you like. Then you would not have to use it when compiling the ckitdemo.c. (Just make sure you take the right ones out for whichever compiler you are using). Matter fact, the way the defaults are defined in CKITDEMO.C, and CKITDEMO.H you don't need to have the -DCOMPILER=TURBOC when using TURBO C to compile the ckitdemo.c file or using Turbo C's IDE. Q. My F4, F3, F7, ALT X, ALT N keys do not do have any effect when returning to the BBS. A. These keys are valid only on doors or sysops using the pcboard.sys file. When the code finds a door.sys or Wildcat! info files, it will make no attempt to update a pcboard.sys file. F5 shell to DOS, F8 return to BBS, F9 screen on/off will work with any system. Try and write your door so that the sysop can use pcboard.sys if he is a PCBoard sysop but will also run on other systems as well. Future updates will take into consideration other systems as permitted. See the compatibility chart above. Q. Why all the formfeeds in the documentation? A. This is so that people with access to a copier can print them out, run the printed sheets thru the copier and duplex (print on both sides) the sheets into a manual. If you do not want the form feeds, just do a global replacement with your favorite editor and get rid of them. Q. I thought CKIT required that the users file path be listed also? A. NO. This was used for the CKITDEMO file only. CKIT library does not care one way or another about the users file being open. CKITDEMO is also written to work with ANY system. Ckitdemo is a demostration of how a door can be written to accept any command line given and make adjustments accordingly. Ckitdemo will accept either: ckitdemo.exe c:\pcb\pcboard.sys c:\pcb\main\users ckitdemo.exe c:\pcb\door.sys ckitdemo.exe c:\wc\callinfo.bbs See the open_door() function for more information. Q. Will CKIT work with any systems users file? A. NO. If you require information from the user file it must be be PCBoard 14.x or PCBoard 12.0. However, by doing so you will be limiting your door to the number of systems it can be ran on. I would not recommend using user file info unless your door is being written specifically for PCBoard. Other system files (pcboard.dat, msgs and other systems users file) will be included in the form of source code at a later date. This will allow you to link those with the existing CKIT library functions. Q. What baud rates can CKIT can handle? A. Ckit can handle ANY baud rate from 50 baud to 230K baud. (these are the baud rates it has been used with). The highest baud any standard IBM compt. system can produce is 115K baud. The 230K baud was done on a modified IBM AT by changing the UART's xtal and using 16550A UARTs. Q. I'm using MSC 6.0 and when I compile my program I get a message "warning 'NULL' : macro redefinition"? A. This is not a problem. It is actually a carry over from MSC5.1. If you wish, you can remove the line #define NULL = 0 in the CKIT.H header file. MSC 6.0 redefined their NULL assignment in the stdlib.h file which causes this. You will not get the warning with MSC 5.1 or lower and TURBO C. Q. I'm using TURBOC and when I compile the small model demo program it works fine. But when I re-compile using medium model I get stack overflow fixup errors from the linker. A. TurboC does not delete and re-compile the CKITDEMO.C module. So when it attempts to link the older small model .obj file you created earlier with the medium library, you will get this error. When you switch memory models, you must delete the previous .obj file created using the small memory model. If this happened to be CKITDEMO.C, you would need to delete CKITDEMO.OBJ before changing memory models. Q. Some function keys are not trapped locally. A. Some keys are reserved on the local keyboard for sysop functions. Try to design your door without using the F3, F4, F5, F7, F8, F9 ALT-H, ALT-N, ALT-X. If you have to use these keys, they can be used by the remote keyboard but just be aware, you would not be able to use them on your local keyboard. Q. When linking my program, I get an error - Unresolved external _wait. A. This function was renamed to ck_wait in v1.7. You need to be using the ckit.h header file. There was a conflict with one of Borland's library names. Q. When linking my code with the library in Turbo C, it does not find the ckit_t?.lib's. A. I have found that TLINK seems to totally ignore the LIB= statement set in the enviroment. The only solution I have for now is to put the ckit turbo libraries in the same dir. as your source code. Q. Why does the user security level somtimes show on the status line and sometimes it doesn't? A. PCBoard.sys file does not provide that information. The security level will only show if you are using door.sys, callinfo.bbs (WILDCAT!) or you are using pcboard.sys and open the users file. The status line indicators for pagebell, printer and caller alarm will also not show up if you are using door.sys or callinfo.bbs but will if you are using any version of pcboard.sys from 12.0 up. Q. Will there be any kind of sign off message from CKIT after the program is registered? A. After CKIT is registered, the only message displayed when closing the door will be the one you defined as exit_msg or the default msg "Returning to system ...".